CIFileDialogCustomize Class

Wraps the IFileDialogCustomizeinterface, that exposes methods that allow an application to add controls to a common file dialog.

Include file: AfxNova/CIFileDialogCustomize.inc

Constructors

Creates instances de the CIFileDialogCustomize class.

CONSTRUCTOR (BYVAL pIFileDialog AS IFileDialog PTR)

Usage example

' // Get a pointer to the IFileDialog interface
DIM pfdlg AS IFileDialog PTR = pofd.GetIFileDialogPtr
IF pfdlg THEN
   ' // Initialize an instance of the CIFileDialogCustomize class
   DIM pCust AS CIFileDialogCustomize = pfdlg
   ' // Relese the IFileDialog interface
   pfdlg->lpvtbl->Release(pfdlg)
   ' // Add controls to the dialog
   IF pCust.GetPtr THEN
      ' Call methods of the CIFileDialogCustomize class
      pCust.AddCheckButton(1001, "My check button", TRUE)
      pCust.AddComboBox(1002)
      pCust.AddEditBox(1003, "My edit control")
      pCust.AddMenu(1004, "My menu")
      pCust.AddPushButton(1005, "My push button")
      pCust.AddSeparator(1006)
      pCust.AddText(1007, "My text")
      pCust.EnableOpenDropDown(1008)
   END IF
END IF

See also a full example at the end of this guide.

CONSTRUCTOR (BYVAL pIFileDialogCustomize AS IFileDialogCustomize PTR, BYVAL fAddRef AS BOOLEAN = TRUE)

Remarks

Useful to be used inside the IFileDialogControlEvents callback class, whose methods pass a pointer to the IFileDialogCustomize interface.

Methods

AddCheckButton

Adds a check button (check box) to the dialog.

FUNCTION AddCheckButton (BYVAL dwIDCtl AS DWORD, BYVAL pwszLabel AS WSTRING PTR, _
   BYVAL bChecked AS BOOLEAN = FALSE) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The default state for this control is enabled and visible.

AddComboBox

Adds a combo box to the dialog.

FUNCTION AddComboBox (BYVAL dwIDCtl AS DWORD) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The default state for this control is enabled and visible.

AddControlItem

Adds an item to a container control in the dialog.

FUNCTION AddControlItem (BYVAL dwIDCtl AS DWORD, BYVAL dwIDItem AS DWORD, BYVAL pwszLabel AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The default state for this item is enabled and visible. Items in control groups cannot be changed after they have been created, with the exception of their enabled and visible states.

Container controls include option button groups, combo boxes, drop-down lists on the Open or Save button, and menus.

AddEditBox

Adds an edit box control to the dialog.

FUNCTION AddEditBox (BYVAL dwIDCtl AS DWORD, BYVAL pwszLabel AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The default state for this control is enabled and visible.

To add a label next to the edit box, place it in a visual group with StartVisualGroup.

AddMenu

Adds a menu to the dialog.

FUNCTION AddMenu (BYVAL dwIDCtl AS DWORD, BYVAL pwszLabel AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The default state for this control is enabled and visible.

To add items to this control, use AddControlItem.

AddPushButton

Adds a button to the dialog.

FUNCTION AddPushButton (BYVAL dwIDCtl AS DWORD, BYVAL pwszLabel AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The default state for this control is enabled and visible.

AddRadioButtonList

Adds an option button (also known as radio button) group to the dialog.

FUNCTION AddRadioButtonList (BYVAL dwIDCtl AS DWORD) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The default state for this control is enabled and visible.

AddSeparator

Adds a separator to the dialog, allowing a visual separation of controls.

AddSeparator (BYVAL dwIDCtl AS DWORD) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The default state for this control is enabled and visible.

AddText

Adds text content to the dialog.

FUNCTION AddText (BYVAL dwIDCtl AS DWORD, BYVAL pwszText AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The default state for this control is enabled and visible.

EnableOpenDropDown

Enables a drop-down list on the Open or Save button in the dialog.

FUNCTION EnableOpenDropDown (BYVAL dwIDCtl AS DWORD) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The Open or Save button label takes on the text of the first item in the drop-down. This overrides any label set by IFileDialog::SetOkButtonLabel.

Use AddControlItem to add items to the drop-down.

EndVisualGroup

Stops the addition of elements to a visual group in the dialog.

FUNCTION EndVisualGroup () AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

GetCheckButtonState

Gets the current state of a check button (check box) in the dialog.

FUNCTION GetCheckButtonState (BYVAL dwIDCtl AS DWORD) AS BOOLEAN

Return value

TRUE means checked; FALSE, unchecked.

GetControlItemState

Gets the current state of an item in a container control found in the dialog.

FUNCTION GetControlItemState (BYVAL dwIDCtl AS DWORD, BYVAL dwIDItem AS DWORD, BYREF dwState AS CDCONTROLSTATEF) AS HRESULT

Return value

A member of the CDCONTROLSTATE enumeration that indicates the current state of the control.

Remarks

The default state of a control item is enabled and visible. Items in control groups cannot be changed after they have been created, with the exception of their enabled and visible states.

Container controls include option button groups, combo boxes, drop-down lists on the Open or Save button, and menus.

GetControlState

Gets the current visibility and enabled states of a given control.

FUNCTION GetControlState (BYVAL dwIDCtl AS DWORD) AS CDCONTROLSTATEF

Return value

A member of the CDCONTROLSTATE enumeration that indicates the current state of the control.

GetEditBoxText

Gets the current text in an edit box control.

FUNCTION GetEditBoxText (BYVAL dwIDCtl AS DWORD) AS DWSTRING

Return value

The text of the edit box control.

GetSelectedControlItem

Gets a particular item from specified container controls in the dialog.

FUNCTION GetSelectedControlItem (BYVAL dwIDCtl AS DWORD) AS DWORD

Return value

The ID of the item that the user selected in the control.

Remarks

To determine the user’s final choice, this method can be called on option button groups, combo boxes, and drop-down lists on the Open or Save button after the dialog has closed. This method cannot be called on menus.

For option button groups and combo boxes, this method can also be called while the dialog is showing, to determine the current choice.

MakeProminent

Places a control in the dialog so that it stands out compared to other added controls.

FUNCTION MakeProminent (BYVAL dwIDCtl AS DWORD) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This method causes the control to be placed near the Open or Save button instead of being grouped with the rest of the custom controls.

Only check buttons (check boxes), push buttons, combo boxes, and menus—or a visual group that contains only a single item of one of those types—can be made prominent.

Only one control can be marked in this way. If a dialog has only one added control, that control is marked as prominent by default.

RemoveControlItem

Removes an item from a container control in the dialog.

FUNCTION RemoveControlItem (BYVAL dwIDCtl AS DWORD, BYVAL dwItem AS DWORD) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Container controls include option button groups, combo boxes, drop-down lists on the Open or Save button, and menus.

SetCheckButtonState

Sets the state of a check button (check box) in the dialog.

FUNCTION SetCheckButtonState (BYVAL dwIDCtl AS DWORD, BYVAL bCkecked AS BOOLEAN) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SetControlItemState

Sets the current state of an item in a container control found in the dialog.

FUNCTION SetControlItemState (BYVAL dwIDCtl AS DWORD, BYVAL dwIDItem AS DWORD, BYVAL dwState AS CDCONTROLSTATEF) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The default state of a control item is enabled and visible. Items in control groups cannot be changed after they have been created, with the exception of their enabled and visible states.

Container controls include option button groups, combo boxes, drop-down lists on the Open or Save button, and menus.

SetControlItemText

Sets the text of a control item. For example, the text that accompanies a radio button or an item in a menu.

FUNCTION SetControlItemText (BYVAL dwIDCtl AS DWORD, BYVAL dwIDItem AS DWORD, BYVAL pwszLabel AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The default state of a control item is enabled and visible. Items in control groups cannot be changed after they have been created, with the exception of their enabled and visible states.

Container controls include option button groups, combo boxes, drop-down lists on the Open or Save button, and menus.

SetControlLabel

Sets the text associated with a control, such as button text or an edit box label.

FUNCTION SetControlLabel (BYVAL dwIDCtl AS DWORD, BYVAL pwszLabel AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Control labels can be changed at any time, including when the dialog is visible.

SetControlState

Sets the current visibility and enabled states of a given control.

FUNCTION SetControlState (BYVAL dwIDCtl AS DWORD, BYVAL dwState AS CDCONTROLSTATEF) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

When the dialog is shown, controls cannot be added or removed, but the existing controls can be hidden or disabled at any time.

SetEditBoxText

Sets the text in an edit box control found in the dialog.

FUNCTION SetEditBoxText (BYVAL dwIDCtl AS DWORD, BYVAL pwszText AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SetSelectedControlItem

Sets the selected state of a particular item in an option button group or a combo box found in the dialog.

FUNCTION SetSelectedControlItem (BYVAL dwIDCtl AS DWORD, BYVAL dwIDItem AS DWORD) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

StartVisualGroup

Declares a visual group in the dialog. Subsequent calls to any “add” method add those elements to this group.

FUNCTION StartVisualGroup (BYVAL dwIDCtl AS DWORD, BYVAL pwszLabel AS WSTRING PTR) AS HRESULT

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Controls will continue to be added to this visual group until you call EndVisualGroup.

A visual group can be hidden and disabled like any other control, except that doing so affects all of the controls within it. Individual members of the visual group can also be hidden and disabled singly.

Example code

#define _WIN32_WINNT &h0602
#include once "AfxNova/CWindow.inc"
#include once "AfxNova/CIOpenSaveFile.inc"
#include once "AfxNova/CIFileDialogEvents.inc"
#include once "AfxNova/CIFileDialogCustomize.inc"
USING AfxNova

DIM pofd AS CIOpenFileDialog
' // Set the file types
pofd.AddFileType("FB code files", "*.bas;*.inc;*.bi")
pofd.AddFileType("Executable files", "*.exe;*.dll")
pofd.AddFileType("All files", "*.*")
pofd.SetFileTypes()
' // Multiple selection (default is single selection)
DIM options AS FILEOPENDIALOGOPTIONS = pofd.GetOptions
pofd.SetOptions(options OR FOS_ALLOWMULTISELECT)
' // Optional: Set the title of the dialog
'   pofd.SetTitle("A Single-Selection Dialog")
' // Set the folder
pofd.SetFolder(CURDIR)
pofd.SetDefaultExtension("bas")
pofd.SetFileTypeIndex(1)

' // Customization --------------------------------------------
DIM pfdlg AS IFileDialog PTR = pofd.GetIFileDialogPtr
IF pfdlg THEN
   DIM pCust AS CIFileDialogCustomize = pfdlg
   pfdlg->lpvtbl->Release(pfdlg)
   IF pCust.GetPtr THEN
      ' Call methods of the CIFileDialogCustomize class
      pCust.AddCheckButton(1001, "My check button", TRUE)
      pCust.AddComboBox(1002)
      pCust.AddEditBox(1003, "My edit control")
      pCust.AddMenu(1004, "My menu")
      pCust.AddPushButton(1005, "My push button")
      pCust.AddSeparator(1006)
      pCust.AddText(1007, "My text")
      pCust.EnableOpenDropDown(1008)
   END IF
END IF
' // --------------------------------------------------------

' // Set events
DIM pfde AS ANY PTR = NEW CIFileDialogEvents
pofd.SetEvents(pfde)

' // Display the dialog
DIM hr AS HRESULT = pofd.ShowOpen(hwnd)

' // Folder name
OutputDebugStringW "Folder name: ";  pofd.GetFolder

' *** Single selection ***
' // Get the result
'IF hr = S_OK THEN
'   OutputDebugStringW pofd.GetResultString
'END IF

' *** Multiple selection ***
IF hr = S_OK THEN
   DIM dwsRes AS DWSTRING = pofd.GetResultsString
   FOR i AS LONG = 1 TO pofd.GetResultsCount
      OutputDebugStringW pofd.ParseResults(dwsRes, i)
   NEXT
END IF